home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / sbin / install-docs < prev    next >
Encoding:
Text File  |  2009-02-09  |  10.3 KB  |  414 lines

  1. #!/usr/bin/perl
  2. # vim:cindent:ts=2:sw=2:et:fdm=marker:cms=\ #\ %s
  3. #
  4. # $Id: install-docs.in 162 2008-11-16 21:36:09Z robert $
  5.  
  6. use warnings;
  7. use strict;
  8.  
  9.  
  10. # declared in Debian::DocBase::InstallDocs;
  11. use vars qw($fully_functional $opt_verbose $opt_debug $opt_update_menus $opt_rootdir $exitval
  12.             $MODE_INSTALL $MODE_REMOVE $MODE_REMOVE_ALL $MODE_INSTALL_ALL
  13.             $MODE_DUMP_DB $MODE_INSTALL_CHANGED
  14.             $MODE_STATUS $MODE_CHECK);
  15.  
  16. my $version='0.8.20';
  17.  
  18. BEGIN {
  19.   if ($ENV{'DPKG_MAINTSCRIPT_PACKAGE'} && $ENV{'DPKG_MAINTSCRIPT_PACKAGE'} ne "doc-base") {
  20.     print STDERR "install-docs called from ".
  21.                   $ENV{'DPKG_MAINTSCRIPT_PACKAGE'} . "'s maintainer script, exiting\n"
  22.       if $ENV{'DOC_BASE_DEBUG'};
  23.     exit 0;
  24.   }
  25.   $fully_functional = eval {
  26.                               require Pod::Usage;
  27.                               import Pod::Usage qw(pod2usage);
  28.                               require Debian::DocBase::Common;
  29.                               import Debian::DocBase::Common;
  30.                               require Debian::DocBase::InstallDocs;
  31.                               import Debian::DocBase::InstallDocs;
  32.                               require Debian::DocBase::Utils;
  33.                               import Debian::DocBase::Utils;
  34.                               1;
  35.                         };
  36.   warn $@ if $@;
  37. }
  38.  
  39. =head1 NAME
  40.  
  41. install-docs - manage online Debian documentation
  42.  
  43. =cut
  44.  
  45.  
  46.  
  47. # set umask explicitly
  48. umask 022;
  49.  
  50. # constants
  51. my $do_dwww_update = 1;
  52. my $force_reregister_flagfile = "/var/lib/doc-base/info/FORCE-REREGISTER.flag";
  53.  
  54. =head1 SYNOPSIS
  55.  
  56.  install-docs [options] -i,--install | -r,--remove | -c,--check file [ file ... ]
  57.  
  58.  install-docs [options] -I,--install-all | -C,--install-changed | -R,--remove-all
  59.  
  60.  install-docs [options] -s,--status docid [ docid ... ]
  61.  
  62.  install-docs [options] --dump-db dbname
  63.  
  64.  install-docs -h,--help | -V,--version
  65.  
  66.  
  67. =head1 DESCRIPTION
  68.  
  69. B<install-docs> is a tool allow Debian package maintainers to register
  70. documentation to various documentation systems.  It currently supports
  71. B<dhelp>,  B<dwww>, B<doc-central>, and B<scrollkeeper> browsers.
  72.  
  73. This manual page provides a quick synopsis of B<install-docs> usage.
  74. Full documentation can be found in the documentation, including a
  75. description of the control file syntax and grammar.
  76.  
  77. =head1 OPTIONS
  78.  
  79. =over 4
  80.  
  81. =cut
  82.  
  83. sub CheckFunctionality(;$) { # {{{
  84.   my $dont_force_reg = shift;
  85.   if (not $fully_functional) {
  86.     open F, "> $force_reregister_flagfile"
  87.       or die "Cannot create $force_reregister_flagfile: $!\n";
  88.     print F "x";
  89.     close F;
  90.     exit 0;
  91.   }
  92.   if (!$dont_force_reg && -e $force_reregister_flagfile) {
  93.     Inform("Force re-registation of all documents");
  94.     SetMode($MODE_INSTALL_ALL);
  95.     unlink ($force_reregister_flagfile);
  96.     return 1;
  97.   }
  98.   return 0;
  99.  
  100. } # }}}
  101.  
  102.  
  103. #### Parse arguments loop #####
  104. #
  105. exit(1) if not $fully_functional and $#ARGV < 0;
  106. pod2usage(-verbose => 0, -exitval => 1) if $#ARGV < 0 ;
  107. while (my $arg = shift @ARGV) {
  108.  
  109.   # try to handle concatenation of options e.g. `-vdi' instead of `-v -d -i'
  110.   if ($arg =~ /^(-\w)(\w+)$/) {
  111.     $arg = $1;
  112.     unshift(@ARGV, "-".$2)
  113.   }
  114.  
  115.   if (($arg eq '-v') or ($arg eq '--verbose')) { # {{{
  116.  
  117. =item B<-v>, B<--verbose>
  118.  
  119. Operate verbosely.
  120.  
  121. =cut
  122.     $opt_verbose = 1;
  123.     next;  # }}}
  124.  
  125.    } elsif (($arg eq '-d') or ($arg eq '--debug')) { # {{{
  126.  
  127. =item B<-d>, B<--debug>
  128.  
  129. Print some debugging informations.
  130.  
  131. =cut
  132.     $opt_debug = 1;
  133.     next;  # }}}
  134.  
  135.    } elsif ($arg eq '--no-update-menus') { # {{{
  136.  
  137. =item B<--no-update-menus>
  138.  
  139. Inhibit running L<dwww-build-menu(8)>, L<dhelp_parse(8)>,
  140. and L<scrollkeeper-update(8)>.
  141.  
  142. =cut
  143.     $opt_update_menus = 0;
  144.     next; # }}}
  145.  
  146.    } elsif ($arg eq '--rootdir') { # {{{
  147.  
  148. =item B<--rootdir> I<dir>
  149.  
  150. Set the root directory to I<dir> instead of `I</>'. Useful and valid only with
  151. the B<--check> action.
  152.  
  153. =cut
  154.     ($#ARGV == -1) and die "Arguments missing for `rootdir'";
  155.     $arg = shift @ARGV;
  156.     -d $arg or die "`$arg' does not exist or is not a directory";
  157.     ($opt_rootdir = $arg) =~ s/\/+$//;
  158.     next; # }}}
  159.  
  160.  
  161. =back
  162.  
  163. =head1 ACTIONS
  164.  
  165. Below is list of possible actions B<install-docs> could handle. There can be only one action
  166. option passed to install-docs, moreover the action with its arguments must be the last option
  167. passed.
  168.  
  169. Each I<file> argument should be the full path for the doc-base control file (i.e.
  170. `/usr/share/doc-base/some_file' or `/etc/doc-base/documents/some_file'), and each
  171. I<docid> should be the document identifier
  172. (Document identifiers are set in the `Document' field of the control file, and usually
  173. correspond to the package name.)
  174.  
  175. If I<file> or I<docid> equals `B<->' (the minus sign), the list of
  176. arguments is read from the standard input (each file name or document id in separate line).
  177.  
  178. =over 4
  179.  
  180.  
  181. =cut
  182.  
  183.    } elsif (($arg eq '-i') or ($arg eq '--install')) { # {{{
  184.  
  185. =item B<-i> I<file> [I<file> ...],  B<--install> I<file> [I<file> ...]
  186.  
  187. Install the documentation described by the control file I<file>.
  188.  
  189. =cut
  190.     # install new docs
  191.     ($#ARGV == -1) and die "Arguments missing for `install'";
  192.     SetMode($MODE_INSTALL, @ARGV) unless CheckFunctionality();
  193.     last; # }}}
  194.  
  195.   } elsif (($arg eq '-r') or ($arg eq '--remove')) { # {{{
  196.  
  197. =item B<-r> I<file> [I<file> ...],  B<--remove> I<file> [I<file> ...]
  198.  
  199. Remove the documentation identified by the control file
  200. I<file>.
  201.  
  202. =cut
  203.     # remove old docs #
  204.     ($#ARGV == -1) and die "Arguments missing for `remove'";
  205.     SetMode($MODE_REMOVE, @ARGV) unless CheckFunctionality();
  206.     last; # }}}
  207.  
  208.   } elsif (($arg eq '-c') or ($arg eq '--check')) { # {{{
  209.  
  210. =item B<-c> I<file> [I<file> ...],  B<--check> I<file> [I<file> ...]
  211.  
  212. Check the control file I<file> and display number of possible problems found.
  213. Use with I<--verbose> to get the actual locations of errors and warnings.
  214. If I<--rootdir> was also given, its argument will be prepended to names of the files
  215. given if the `Files' and `Index' fields of the I<file>.
  216.  
  217. =cut
  218.     ($#ARGV == -1) and die "Arguments missing for `check'";
  219.     SetMode($MODE_CHECK, @ARGV);
  220.     last; # }}}
  221.  
  222.   } elsif (($arg eq '-R') or ($arg eq '--remove-all')) { # {{{
  223.  
  224. =item B<-R>,  B<--remove-all>
  225.  
  226. De-register all registered documents.
  227.  
  228. =cut
  229.     ($#ARGV == -1) or die "Too many arguments missing for `remove-all'";
  230.     CheckFunctionality(1);
  231.     SetMode($MODE_REMOVE_ALL);
  232.     last; # }}}
  233.  
  234.   } elsif (($arg eq '-I') or ($arg eq '--install-all')) { # {{{
  235.  
  236. =item B<-I>, B<--install-all>
  237.  
  238. (Re)register all documents from F</usr/share/doc-base> and F</etc/doc-base/documents>.
  239.  
  240. =cut
  241.     ($#ARGV == -1) or die "Too many arguments for `install-all'";
  242.     CheckFunctionality(1);
  243.     SetMode($MODE_INSTALL_ALL);
  244.     last; # }}}
  245.  
  246.   } elsif (($arg eq '-C') or ($arg eq '--install-changed')) { # {{{
  247.  
  248. =item B<-C>, B<--install-changed>
  249.  
  250. Compare contents of F</usr/share/doc-base> and F</etc/doc-base/documents> directories
  251. with registered documents database and de-register any files that are missing and
  252. (re)register only changed or new files.
  253.  
  254. =cut
  255.     ($#ARGV == -1) or die "Too many arguments for `install-changed'";
  256.     SetMode($MODE_INSTALL_CHANGED) unless CheckFunctionality();
  257.     last; # }}}
  258.  
  259.   } elsif (($arg eq '-s') or ($arg eq '--status')) {  # {{{
  260.  
  261. =item B<-s> I<docid> [I<docid> ...], B<--status> I<docid> [I<docid> ...]
  262.  
  263. Display the status of the document identifier I<docid>.
  264.  
  265. =cut
  266.     ($#ARGV == -1) and die "Arguments missing for `status'";
  267.     SetMode($MODE_STATUS, @ARGV);
  268.     last; # }}}
  269.  
  270.   } elsif (($arg eq '-L') or ($arg eq '--listfiles')) { # {{{
  271.  
  272. =item B<-L> I<docid> [I<docid> ...], B<--listfiles> I<docid> [I<docid> ...]
  273.  
  274. Deprecated option. Does nothing.
  275.  
  276. =cut
  277.     warn "Ignoring deprecated command line argument: $arg\n";
  278.     exit 0;
  279.  # }}}
  280.  
  281.   }  elsif ($arg eq '--dump-db') { # {{{
  282.  
  283. =item B<--dump-db> I<dbname>
  284.  
  285. Dumps contents of internal databases, for debugging purposes. I<dbname> can be either B<files.db> or
  286. B<status.db>.
  287.  
  288. =cut
  289.     ($#ARGV == 0) or die "`dump-db' requires exactly one argument";
  290.     SetMode($MODE_DUMP_DB, @ARGV);
  291.     last # }}}
  292.  
  293.    } elsif (($arg eq '-h') or ($arg eq '--help')) { # {{{
  294.  
  295. =item B<-h>, B<--help>
  296.  
  297. Show a short help message.
  298.  
  299.  
  300. =cut
  301.     pod2usage(-verbose => 1, -exitval => 0);
  302.     # NOT REACHED  # }}}
  303.  
  304.    } elsif (($arg eq '-V') or ($arg eq '--version')) { # {{{
  305.  
  306. =item B<-V>, B<--version>
  307.  
  308. Display version infromation
  309.  
  310. =back
  311.  
  312. =cut
  313.     print "install-docs $version\n";
  314.     exit 0;
  315.     # NOT REACHED  # }}}
  316.  
  317.   } else { # {{{ default: die
  318.     pod2usage(-msg => "Invalid argument: $arg", -verbose => 0, -exitval => 1);
  319.   } # }}}
  320.  
  321. }
  322.  
  323.  
  324.  
  325. #### Main function
  326. InstallDocsMain();
  327.  
  328.  
  329. exit ($exitval);
  330.  
  331. __DATA__
  332.  
  333. =head1 COMPATIBILITY ISSUES
  334.  
  335. The following features were added in version 0.8.4,
  336. please make sure to add proper
  337. `I<Conflicts>' or `I<Depends>' lines if you would like to use them in your package's scripts:
  338.  
  339. =over
  340.  
  341. =item *
  342.  
  343. support for passing more than one argument to the B<-i> and B<-r> actions,
  344.  
  345. =item *
  346.  
  347. reading arguments from the standard input,
  348.  
  349. =item *
  350.  
  351. B<-I>,B<--install-all>, B<-R>,B<---remove-all>, B<-c>,B<--check> actions,
  352.  
  353. =item *
  354.  
  355. B<-d>,B<--debug>, B<-h>,B<--help> options.
  356.  
  357. =back
  358.  
  359. The B<-C>,B<--install-changed>, B<--dump-db>, B<-V>,B<--version> options were added in 0.8.12.
  360.  
  361. =head1 FILES
  362.  
  363. =over 4
  364.  
  365. =item F</usr/share/doc-base/>
  366.  
  367. The location of doc-base control files provided by various packages.
  368.  
  369. =item F</etc/doc-base/documents/>
  370.  
  371. The location of doc-base control files provided by local administrator.
  372.  
  373. =item F</var/lib/doc-base/info/documents/>
  374.  
  375. The location of registered control files.
  376.  
  377. =item F</var/lib/doc-base/info/status.db>
  378.  
  379. Statuses of registered documents.
  380.  
  381. =item F</var/lib/doc-base/info/files.db>
  382.  
  383. Timestamps and documents ids of registered doc-base files.
  384.  
  385. =item F</var/lib/doc-base/omf/>
  386.  
  387. The location of generated scrollkeeper OMF files.
  388. Note: F</usr/share/omf/doc-base> should be a symbolic link pointing to the directory.
  389.  
  390. =back
  391.  
  392. =head1 BUGS
  393.  
  394. See L<http://bugs.debian.org/doc-base>.
  395.  
  396. =head1 SEE ALSO
  397.  
  398. dhelp(1), doccentral(1), dwww(8), scrollkeeper(7),
  399. Debian doc-base Manual F</usr/share/doc/doc-base/doc-base.html/index.html>
  400.  
  401. =head1 AUTHOR
  402.  
  403. This program was originally written by Christian Schwarz
  404. <schwarz@debian.org>, for the Debian GNU/Linux system, and the
  405. next maintainer was Adam Di Carlo <aph@debian.org>.
  406. Robert Luberda <robert@debian.org> is currently maintaining and extending it.
  407.  
  408. This software was meant to be for the benefit of the entire Debian
  409. user and developer community.  If you are interested in being involved
  410. with this software, please join the mailing list
  411. <debian-doc@lists.debian.org>.
  412.  
  413. =cut
  414.